Introduction

Where Is It? - Description API 2.20

Programmer's Reference

Welcome to the WhereIsIt's Description Application Programming Interface (Description API, or DescAPI), a special feature available to programmers to extend WhereIsIt's capabilities with automatic description importing. For all those new to programming, API is a standardized set of functions and procedures that allow both master program and extension library to communicate. With Description API, your end result will be a DLL library implementing functions described here, therefor allowing itself to integrate in WhereIsIt application.

This document covers both DescAPI 1.0, used in WhereIsIt 2.xx, as well as newer DescAPI 2.xx, used in WhereIsIt 3.xx.

DescAPI versions

DescAPI 1.0
The original DescAPI interface, first introduced in WhereIsIt 2.00 and supporting plugins for importing description information. Plugins written using DescAPI 1.00 can be used in all WhereIsIt 2.00 and later versions.

DescAPI 2.0
A major upgrade to the original DescAPI 1.00, introducing thumbnail plugins, formatting plugins, CDDB plugins, and alias names, among others. DescAPI 2.0 is supported in WhereIsIt 3.00 and newer - DescAPI 2.0 is backward compatible with DescAPI 1.0 (old plugins work with DescAPI 2.0, too), however plugins written using DescAPI 2.0 can not be used in older WhereIsIt 2.xx releases.

DescAPI 2.10
Introduced in WhereIsIt 3.20. Adds support for file name formatting and custom icons plugins. Plugins written for DescAPI 2.10 can be used in all WhereIsIt 3.xx and newer versions, however in older WhereIsIt 3.0x and 3.1x both new plugin types will not be available.

DescAPI 2.20
Supported by WhereIsIt 3.50 and later. The main new feature in this version is the introduction of runtime plugins.


Basic Concepts

Description plugins in WhereIsIt are in form of 32-bit Dynamic Link Libraries (DLL files). You can write and compile a DLL with most Windows programming Languages available today. All of your DLL library functions that are either exported or sent as parameters to WhereIsIt must use the __stdcall calling convention for passing their own parameters.

There are two basic concepts involved while preparing a Description API compliant DLL:

Plugins Module

A plugins module is equal to single DLL file. Each module can include one or more plugins, and WhereIsIt can accept multiple plugins modules to work with at the same time. All communications defined in Description API are going on between WhereIsIt and plugins module.

Plugin

A plugin is a part of module that is capable of importing descriptions or thumbnails from one specific description source - for example, File_id.diz files, or graphics files for plugins. Each plugins module will handle its own plugins, take care about their registration and communication with WhereIsIt.

During plugins module's initialization each module will be called to present itself and register available plugins with WhereIsIt. This way, the program can manage list of available plugins, presenting them to user in order to assign priority, enable or disable them, etc. Later, when a description source is found during disk scan that can be handled by one of registered plugins, its parent module is called with request to provide description or thumbnail from that plugin.


Description Plugin Types

Because of there are different ways how to get a description from different sources, Description API includes definitions about different types of plugins. While all description plugins have a goal to eventually produce a description to be used in WhereIsIt, communication with the main program will differ based on how they can get those descriptions. Each plugin group has its own ID, as defined in Description API:

ptReserved
Plugins of type ptReserved are for WhereIsIt's internal use only. Do not use ptReserved plugin type in your own description modules.
ptSameFile
This is the simplest group of plugins. Plugins of this type can extract description from the same file or folder that will be described in catalog with this description. In other words, file contains description for itself, and plugin will extract it and report it back. Examples of such files could be graphics or audio files - a plugin could return their size, color depth, play length etc. as a description. Plugin will receive the file as a parameter, for which it is expected to return a suitable description.
Import function: | ImportDesc_SameFile (DescAPI 1.0)
 | ImportDesc_SameFileEx (DescAPI 2.xx)
ptParentItem
This group of plugins will return a description from given source file for a parent item, usually a folder where they are located, or an archive file, if source file is compressed inside. A typical example of this group are well known FILE_ID.DIZ files. When description is needed, a plugin of this type will receive a list of all files registered for importing description for their parent item. If more than one such file is available, it is up to the plugin to decide which one to use.
Import function: | ImportDesc_ParentItem (DescAPI 1.0)
 | ImportDesc_ParentItemEx (DescAPI 2.xx)
ptFolder
(DescAPI 2.20 and newer only)
The ptFolder plugins will provide descriptions for individual folders in catalog. Similar to ptSameFile plugins, these plugins handle folders rather than files. Plugin will receive drive and folder's path, and is expected to provide a description or alias name for that folder.
Import function: ImportDesc_FolderEx
ptItemList
This group can provide multiple descriptions from the same source, and is targeted to such description files that hold a list of descriptions for files and folders on media, either in same folder as description file itself, or in subfolders as well. Examples of such description files are FILES.BBS, DESCRIPT.ION, 00INDEX.TXT etc., each holding descriptions for items in the same folder. When plugin of this type is called, it will receive a list of found description files of this type, and an address of function where it will report back each file-description pair it was able to get from the source file(s).
Import function: | ImportDesc_ItemList (DescAPI 1.0)
 | ImportDesc_ItemListEx (DescAPI 2.xx)
ptDiskInfo
Plugins in this group can be used to describe media itself based on its properties, like type, size, serial number, etc. A plugin of this group will receive as a parameter a record off all known details about media. An example that comes to mind would be Audio CD recognition, perhaps even by using one of public Audio CD databases on the Internet.
Import function: | ImportDesc_DiskInfo (DescAPI 1.0)
 | ImportDesc_DiskInfoEx (DescAPI 2.xx)
ptCDDB
(DescAPI 2.xx only)
This is a bit special type of description plugin - unlike the ones described above, ptCDDB is quite specific in its purpose and is also has some additional capabilities. Basically, the ptCDDB group of plugins are used to retrieve information about audio CDs from CDDB database on the Internet. They act the same as plugins registered as both ptSameFile and ptDiskInfo, which is exactly how the CDDB plugin used to be implemented in DescAPI 1.0. In DescAPI 2.0, however, they were made to be a separate type as CDDB queries enjoy some special support in WhereIsIt 3.xx - it is the only type of plugin that can be run at times other than scanning the media, as CDDB info can be imported on request at any time, for any number of selected disks.
Import function: | ImportDesc_DiskInfo (DescAPI 1.0)
 | ImportDesc_SameFileEx (DescAPI 2.xx)

ptFormatting
(DescAPI 2.xx only)
These plugins are different from all other description plugins so far, and they serve a different purpose. Their task is not to retrieve a description, but rather to format one retrieved by one of the plugin types above. There may be many formatting plugins installed, and retrived description may go through many formatting plugins before it is included in catalog. A typical purpose of formatting plugin might be limiting the size of imported description, changing its appearance, or modifying the text inside, for example, performing OEM conversion to change the code page used in the original text.
Associated function: FormatDescription
ptFileNameFormatting
(DescAPI 2.10 and newer only)
Plugins of this type can change the character case (uppercase/lowercase) of scanned file and folder names, as stored in catalog. Note that this applies to actual file names, not alias names. Providing file name formatting plugins allows for customizable adjusting on how file and folder names are stored and displayed in catalog - for example, a common action is to change all uppercase names to sentence case for easier reading (i.e. "TEST" to "Test"). Plugins are only allowed to modify character case without changing the name itself.
Associated function: FormatFileName

ptThumbnails
(DescAPI 2.xx only)
Thumbnails plugins have a different role compared to other description plugins, as they import images rather than textual descriptions. In basics they are similar to the ptSameFile plugins, except their result is an image handle. Plugins are only expected to retrieve the image from the image file format they are handling, and return a standard bitmap handle - any kind of processing the image such as downsampling it to a thumbnail size is not necessary since WhereIsIt will handle that. ptThumbnails plugins are also used by image viewer to display images in full size.
Import function: ImportThumbnail
ptCustomIcons
(DescAPI 2.10 and newer only)
These plugins allows importing of custom icons to be used with drives and folders instead of default system icons. Custom icons are stored in catalogs, just like thumbnails, however they can be shared if multiple drives/folders use the same icon. These plugins can, for example, assign a special icon for specific drive or media type, import a custom CD-ROM icon from its Autorun file, etc.
Import function: ImportCustomIcon

ptRuntime
(DescAPI 2.20 and newer only)
Unlike all other plugins, ptRuntime plugins are not used during media scanning, but rather on user's direct selection via menu option. As ptRuntime plugins are usually not automatic, plugins of this type can provide their own user interface and interact with the user in order to get their job done. For example, such plugins could be some sort of specialized description editors that can work with the user to prepare data to be imported. Their primary task, though, is to allow for importing of data that can not be imported automatically, without some sort of assistance or input from the user.

Import functions: | ImportDesc_SameFileEx
 | ImportDesc_ParentItemEx
 | ImportDesc_FolderEx
 | ImportDesc_DiskInfoEx
 | ImportThumbnail


Drive Type Constants

This is the list of currently supported drive and media types in WhereIsIt:

#define DT_UNKNOWN | 255 | // unknown drive
#define DT_DISKGROUP | 254 | // disk group
---
#define DT_FLOPPY525_360 | 0 | // floppy 5.25" 360 kB
#define DT_FLOPPY525_12 | 1 | // floppy 5.25" 1.2 MB
#define DT_FLOPPY525_720 | 2 | // floppy 3.5" 720 kB
#define DT_FLOPPY525_8SD | 3 | // floppy 8" Single Density
#define DT_FLOPPY525_8DD | 4 | // floppy 8" Double Density
#define DT_HARDDISK | 5 | // hard disk
#define DT_TAPEDRIVE | 6 | // tape drive
#define DT_FLOPPY35_144 | 7 | // floppy 3.5" 1.44 MB
#define DT_OPTICAL | 8 | // optical drive
#define DT_FLOPPY35_288 | 9 | // floppy 3.5" 2.88 MB
#define DT_CDROM | 10 | // CD-ROM
#define DT_NETWORK | 11 | // Network drive
#define DT_RAMDISK | 12 | // RAM disk
#define DT_REMOVABLE | 13 | // generic removable drive
#define DT_ZIPDRIVE | 14 | // iomega ZIP 100
#define DT_JAZDRIVE | 15 | // iomega JAZ 1 GB
#define DT_ZIPDRIVEPLUS | 16 | // iomega ZIP 100 Plus
#define DT_SEAGATEDIRECTTAPE | 17 | // Seagate Direct Tape virtual drive
#define DT_LS120 | 18 | // LS-120 floppy drive
#define DT_MOS320 | 19 | // Deltis MOS320 removable drive
#define DT_MOS332 | 20 | // Olympus MOS332 removable drive
#define DT_M2531A | 21 | // Fujitsu M2531A removable drive
#define DT_JAZ2DRIVE | 22 | // iomega JAZ 2GB
#define DT_ZIP250 | 23 | // iomega ZIP 250
// --- DescAPI 2.0 only ---
#define DT_AUDIOCD | 24 | // audio CD

See also:
DISKINFORECORD, IMPORTDISKINFOREC


Glossary

Alias name
A replacement name for files and folders, used only internally inside catalogs. Each file or folder can have its own alias name, in cases where the original file name is not very informative or friendly. Description plugins can import and set alias names as well as descriptions.
A common example of using alias names is replacing the Audio Track files (Tracknn.cda) with the Title and Author data, retrieved by the CDDB plugin.

Description
A textual, possibly multi-line description of an item in catalog. Every catalog item can have its own description, which is either imported automatically during media scan by description plugins, or edited manually by the user.

Description Module
Description module is a DLL file, used to expand WhereIsIt's description importing capabilities. Each description module can contain one or more description plugin.

Plugins
Description plugins are an add-ons for WhereIsIt that allow automated description importing from different sources. Mostly plugins are used for importing textual descriptions, however some plugins types also handle formatting of imported descriptions, or they import image thumbnails.

Thumbnail
A small graphical representation of a document, most commonly used on image file. WhereIsIt can import such small versions of image files and store them inside catalogs, making them available for preview even when files themselves are not available.


Description API 1.0 Functions

This is the list of all available functions defined in Description API version 1.0 in order to provide a way for WhereIsIt and description module to communicate. Some of these functions are required to be present and exported in description module, while some are optional. Function set has been kept as minimal as possible, in order to simplify programming of plugins. Programmer should be able to keep focus on how to get description from required source while WhereIsIt will take care of the rest.

Please note:
Description API 1.0 is defined and used in WhereIsIt 2.xx - newer WhereIsIt 3.xx uses the enhanced Description API 2.0. All new plugins should be developed complying to DescAPI 2.0 if they are to be used in WhereIsIt 3.xx and newer. Plugins complying to DescAPI 1.0 will still work in both WhereIsIt 2.xx and WhereIsIt 3.xx, however their capabilities in WhereIsIt 3.xx will be limited compared to native DescAPI 2.0 plugins.

Description Module Initialization
ModuleInfo | ( required )
RegisterDescPlugins | ( required )
ConfigPluginProc | ( optional )
Description Importing
InitDescImport | ( optional )
DoneDescImport | ( optional )
ImportDesc_SameFile | ( required if plugins of type ptSameFile are registered)
ImportDesc_ParentItem | ( required if plugins of type ptParentItem are registered)
ImportDesc_ItemList | ( required if plugins of type ptItemList are registered)
ImportDesc_DiskInfo | ( required if plugins of type ptDiskInfo are registered)
Callback functions
RegisterPlugin | ( callback )
RequireFile | ( callback )
StoreDescProc | ( callback )

Legend:

required functions must be present and exported in your DLL in order to be used in WhereIsIt. WhereIsIt will not accept DLL missing those functions as a valid description module.

optional functions are provided for your convenience and will be called from WhereIsIt if they are exported in your DLL. You can use them if you need them with description importing.

callback functions are defined in WhereIsIt, their addresses will be passed to one of your DLL-defined functions as parameters. Those functions are provided for description modules to pass back information to WhereIsIt, or to employ some of WhereIsIt's capabilities during description importing.


ModuleInfo()

REQUIRED - DescAPI version: 1.0

The ModuleInfo function is the first one called by WhereIsIt when collecting data about available plugins. This function will present your Description module's name, author, and version to WhereIsIt. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

VOID ModuleInfo(
LPTCSTR lpszModuleName // address of buffer to store module name
LPTCSTR lpszAuthor // address of buffer to store author's name
LPTCSTR lpszVersion // address of buffer to store version string
);

Parameters
lpszModuleName
Points to the buffer to receive the null-terminated string containing the module's name. String may not exceed 1024 bytes in length. Example: 'WhereIsIt Description Module'.
lpszAuthor
Points to the buffer to receive the null-terminated string containing the author's name. String may not exceed 1024 bytes in length. Example: 'Robert Galle'.
lpszVersion
Points to the buffer to receive the null-terminated string containing the version number. String may not exceed 1024 bytes in length. Example: '0.90 beta'.

Return Values
None.

Remarks
If any of the strings is returned empty, WhereIsIt will not register or use this module.
Modules written for WhereIsIt 3.xx and newer should use the DescAPI 2.xx equivalent instead, the ModuleInfoEx.

See also:
ModuleInfoEx


RegisterDescPlugins()

OPTIONALLY REQUIRED - DescAPI version: 1.0, 2.xx

The RegisterDescPlugins function is called during module initialization. Description module is expected to provide WhereIsIt with information about available description plugins in this module. RegisterDescPlugins function receives as a parameter the address of callback function to be used for registering plugins. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

VOID RegisterDescPlugins(
PROC lpRegisterPlugin, // pointer to a callback function
);

Parameters
lpRegisterPlugin
Points to the address of WhereIsIt-defined function to call when registering a new plugin. See the RegisterPlugin function description for details.

Return Values
None.

Remarks
You may want to store the address of lpRegisterPlugin callback procedure in case you will need it later, too. You can call again this procedure to re-register plugin in WhereIsIt in case some of data has changed - for example, plugin can have a configure dialog where user can change some details about the plugin.

See also:
RegisterPlugin


ConfigPluginProc()

OPTIONAL - DescAPI version: 1.0, 2.xx

The ConfigPluginProc is a function provided inside description module, and provides everything necessary for user to configure specified plugin - create and show appropriate dialog, load and store settings etc. Each plugin in description module can have assigned its own config function, or some of them (or all) can share the same one. Config function for each plugin is specified as a part of plugin registration, using the RegisterPlugin.

VOID ConfigPluginProc(
HINSTANCE hInstance, // handle to application instance
HWND hWndParent, // handle to parent or owner window
WORD wPluginID // ID of plugin to configure
);

Parameters
hInstance
Identifies the instance of the module to be associated with the window.
hWndParent
Identifies the parent or owner window of any window, created by config function.
wPluginID
Contains plugin ID number to be used as a reference to this plugin. When WhereIsIt will call one of description importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.

Return Values
None.

Remarks
If your config procedure(s) need place to store their settings, you can use a special key in the registry. This key is reserved for all plugins used in WhereIsIt - each plugin should create its own key under Settings to store the data:
HKEY_CURRENT_USER\SOFTWARE\SearchSoft\Where Is It?\Plugins\Settings

See also:
RegisterPlugin


InitDescImport()

OPTIONAL - DescAPI version: 1.0, 2.xx

The InitDescImport is optional and only called if your description module exports a function by this name. It does not have any parameters, and does not return any result - this is just a way for WhereIsIt to notify all interested description modules that disc scan operation is just about to begin, or description plugin operations will begin for a given disk. If any of your plugins need to be initialized or prepared in some other way before they can start importing data, this is the place to do it.

VOID InitDescImport(VOID)

Parameters
None.

Return Values
None.

Remarks
If there is an operation in progress that will involve importing descriptions from more than one media (for example, a CDDB query for multiple audio CDs), InitDescImport and DoneDescImport are called before and after each disk is processed.

See also:
DoneDescImport, InitVCLPlugin


DoneDescImport()

OPTIONAL - DescAPI version: 1.0, 2.xx

The DoneDescImport is optional and only called if your description module exports a function by this name. WhereIsIt will call this function when disk scanning has completed, or all description plugin operations on given disk are completed. This function provides a way to clean up after plugins have done their job.

VOID DoneDescImport(VOID)

Parameters
None.

Return Values
None.

Remarks
If there is an operation in progress that will involve importing descriptions from more than one media (for example, a CDDB query for multiple audio CDs), InitDescImport and DoneDescImport are called before and after each disk is processed.

See also:
InitDescImport


ImportDesc_SameFile()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_SameFile function is the main import function for plugins of type ptSameFile. WhereIsIt will call this function during disk scan every time when a file is found that matches the file mask of one of ptSameFile plugins in your module. WhereIsIt will expect from this function to do required processing on provided file (using requested description plugin), and return appropriate description.

BOOL ImportDesc_SameFile(
WORD wPluginID, // ID of description plugin to be used with provided file
LPTCSTR lpszFileName, // points to a null-terminated string with full path to the file
LPTSTR lpszDesc, // address of buffer to receive description
PROC lpRequireFileProc // address of RequireFile callback function
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptSameFile registered in your description module, then the ImportDesc_SameFile function must check the wPluginID parameter and activate the proper plugin.
lpszFileName
Points to the null-terminated string, containing a full path to the file waiting to be described. Provide this parameter to the RequireFile function before your plugin attempts to open the file.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values
Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks
If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types, RequireFile, ImportDesc_SameFileEx


ImportDesc_ParentItem()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_ParentItem function is called by WhereIsIt when program needs to import description from one of module's ptParentItem plugins, and some of found files are matching plugin's file mask. Plugin will receive a list of matching files, and is expected to extract description to be assigned to the parent item (usually a parent folder, or an archive file, where found files are compressed in).

BOOL ImportDesc_ParentItem(
WORD wPluginID, // ID of description plugin to be used with provided file
LPTCSTR lpszParentName, // points to null-terminated string with parent item's path
LPTCSTR lpszFileList, // points to a double - null-terminated list of found files
LPTSTR lpszDesc, // address of buffer to receive description
PROC lpRequireFileProc // address of RequireFile callback function
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ParentItem function must check the wPluginID parameter and activate the proper plugin.
lpszParentName
Points to the address of a null-terminated string, holding a full path to the parent item (item that will receive description provided by calling this function).
lpszFileList
Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:
  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0
where #0 represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file. Files in the list are sorted in the same order as are plugin's mask, preserving priorities. For example, if plugin is set to import "*.aaa,*.bbb" files, all aaa files will be listed first, followed by all bbb files.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values
Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks
If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types, RequireFile, ImportDesc_ParentFileEx,


ImportDesc_ItemList()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_ItemList function is a front-end for ptItemList - typed plugins. This function will be called by WhereIsIt when some of files are found to match the plugin's file mask, and plugin is given a chance to import descriptions from them. Since plugins of this type can retrieve multiple description from the source, a callback function is provided for a plugin to report the extracted descriptions back to WhereIsIt.

VOID ImportDesc_ItemList(
WORD wPluginID, // ID of description plugin to be used with provided file
LPTCSTR lpszParentName, // points to null-terminated string with parent item's path
LPTCSTR lpszFileList, // points to a double - null-terminated list of found files
PROC lpRequireFileProc, // address of RequireFile callback function
PROC lpStoreDescProc // address of StoreDescProc callback function
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptItemList registered in your description module, then the ImportDesc_ItemList function must check the wPluginID parameter and activate the proper plugin.
lpszParentName
Points to the address of a null-terminated string, holding the full path to parent item (parent folder or compressed archive file holding the found files).
lpszFileList
Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:
  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0
where #0 represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file.
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
lpStoreDescProc
Holds the address of StoreDescProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreDescProc for more details.

Return Values
None.

See also:
Plugin Types, RequireFile, StoreDescProc, ImportDesc_ItemListEx


ImportDesc_DiskInfo()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_DiskInfo function is called for plugins of ptDiskInfo.

BOOL ImportDesc_DiskInfo(
WORD wPluginID, // ID of description plugin to be used for importing
LPDISKINFOREC lpDiskInfo, // points to the DISKINFORECORD
LPTSTR lpszDesc // address of buffer to receive description
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to retrieve description for given disk. If there are more plugins of type ptDiskInfo registered in your description module, then the ImportDesc_DiskInfo function must check the wPluginID parameter and activate the proper plugin.
lpDiskInfo
Points to the DISKINFORECORD structure, containing details about media that is being scanned.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

Return Values
Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks
If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types


RegisterPlugin()

CALLBACK - DescAPI version: 1.0, 2.xx

The RegisterPlugin function is provided by WhereIsIt, and is received as a parameter with the RegisterDescPlugins function. Your module will call RegisterPlugin from the RegisterDescPlugins function, once for each description plugin available in your module. Parameters to this function will provide everything WhereIsIt needs to know about the specified plugin.

INT RegisterPlugin(
 WORD wPluginID, // unique plugin's ID inside your description module
BYTE byPluginType, // specifies plugin type
LPTCSTR lpszPluginName, // specifies the name of the plugin, as visible to users
LPTCSTR lpszPluginMask, // address of buffer to store plugin's target file masks
PROC lpConfigProc // address of function used to configure plugin
);

Parameters
wPluginID
Contains plugin's ID number to be used as a reference to this plugin. When WhereIsIt will call one of description-importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.
byPluginType
Specifies the type of plugin.
lpszPluginName
Specifies the name of the plugin, as users will see it in WhereIsIt.
lpszPluginMask
Points to a null-terminated string buffer where you can put a list of files or file masks. This is the list of files that your plugin can extract description(s) from. For example, a plugin that can extract information from WAV files and use it to describe those file will provide "*.WAV" as a plugin mask. If during disk scan one or more files complying with specified mask are encountered, your plugin will be called to extract description from them. Files or file masks in string should be provided in UPPER-CASE and separated with commas. Example: "README.TXT, *.NFO".
lpConfigProc
Points to the function that can be used to setup your plugin. This function will be called if user will select your plugin in WhereIsIt, and click the Configure button. If your plugin does not provide users with ability to configure the plugin, you can specify NULL here as a parameter.

Return Values
If returned value is equal or greater to zero, plugin was successfully registered with WhereIsIt and return value is plugin's assigned serial number on WhereIsIt's plugin list. This value is informative only and will not be referenced later, you may safely discard it.

Negative return value is an error code, by the following table:

-1 | Invalid plugin type
-2 | Plugin with this ID already exists in your module
-3 | The name of plugin is invalid
-4 | File mask provided for plugin is invalid
-5 | Module does not export required description function for this plugin type

Note that error code -2 only applies if trying to register a plugin of different type than the one already registered with the same ID. If both plugins have the same ID and are of the same type, WhereIsIt will adjust settings for existing plugin instead of registering a new one.

See also:
RegisterDescPlugins, PluginDefaultStateProc, plugin types


RequireFile()

CALLBACK - DescAPI version: 1.0, 2.xx

The RequireFile function is provided by WhereIsIt, and is used by plugins whenever they need to access a specific file. The address of this function to call is provided as a parameter to each of description importing functions - ImportDesc_ xxx. Function will return a new string, containing a full path to the requested file that plugin can now actually open and use.

The main purpose of this function is to unpack description files, if they are compressed inside archives. If such compressed file is requested by plugin via RequireFile function, WhereIsIt will first unpack it to temporary folder, and return the full path to the uncompressed file. Temporary files will be removed as soon as the plugin is finished with importing current description and returns control back to WhereIsIt.

LPTSTR RequireFile(
LPTCSTR lpszFileName // path to the file to access
);

Parameters
lpszFileName
Points to the null-terminated string containing a path to file that plugin would like to use. Path to file should be the same one as provided by WhereIsIt to the ImportDesc_xxx function.

Return Values
Returns a pointer to null-terminated string, containing full path to the requested file that plugin can use. This path is not necessary the same as the one provided as parameter to this function.

Remarks
Make sure that you use this function to request access to any file used by the plugin during description importing.

See also:
Plugin Types, ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList
ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx, ImportThumbnail


StoreDescProc()

CALLBACK - DescAPI version: 1.0, 2.xx

The StoreDescProc function is provided by WhereIsIt, and its address is sent as a parameter to ImportDesc_ItemList and ImportDesc_ItemListEx functions. Those functions are used to import description using ptItemList plugins, meaning it will possibly return multiple descriptions from single description source. The purpose of StoreDescProc function is to provide a way for ImportDesc_ItemList function to send each retrieved "file name"-"description" pair back to WhereIsIt, where the description will be stored in the catalog by the specified file.

BOOL StoreDescProc(
LPTCSTR lpszFileName, // points to retrieved file name
LPTCSTR lpszDesc // points to retrieved description string
);

Parameters
lpszFileName
Points to the null-terminated string containing name and optional path to file or folder. WhereIsIt will try to find this item among catalogued data, and attach to it the description provided as the next parameter. See Remarks below for additional details.
lpszDesc
Points to the null-terminated string containing a description retrieved by plugin that belongs to the lpszFileName parameter.
WARNING: Length of provided description should not exceed the maximum allowed description size, limited by MaxDescLength global constant (currently set to 4 kB). If description is longer, it will be truncated.

Return Values
Returns TRUE if description was successfully stored in catalog, or FALSE, if provided file name was not found in the catalog.

Remarks
File or folder name can be provided in any of these three forms: name only, name with relative path from current folder, or file name with full path to item on the disk.
  • If target item is located in the same folder as description file is, you should provide the lpszFileName parameter as plain file name only, for example "TEST.EXE". This is also the most optimal choice from performance point of view since program is optimized to quickly find items in current folder. Most of description file formats like INDEX.TXT or FILES.BBS include list of files for current folder only, so you should be able to use this mode as much as possible.
  • If target is located in one of subfolders, relative to folder with the description file, you can use addressing with relative path, for example "FOLDER1\FOLDER2\...\TEXT.EXE". WhereIsIt will start in the current folder and look in catalog for subfolder named Folder1. If provided subfolder exist in catalog, WhereIsIt will look for file, too, and append description if file is found.
  • If you would like to provide descriptions for items anywhere on the disk, you will have to provide full path to the target file, including the drive letter, for example "F:\CURRENT\FOLDER1\FOLDER2\TEST.EXE".
    WARNING: This mode is only allowed when user is importing descriptions on demand, in already catalogued data, and will always fail when you try to use it during the disk scan.
Note: The last two modes can be considerably slower compared to the first one, especially if there are many subfolders in the disk you are scanning. If there are many items to import, end user may be experiencing considerable delays while your plugin is active.

See also:
ImportDesc_ItemListEx, StoreAliasProc


Description API 1.0 Structures

The following constants and structures are defined as a part of Description API v1.0:

Structures

DISKINFORECORD

Constants

PluginType
MaxDescLength
DriveTypes


DISKINFORECORD

DescAPI version: 1.0, 2.xx

The DISKINFORECORD structure is used with ImportDesc_DiskInfo, ImportDesc_DiskInfoEx, and ValidateRuntimePlugin, and functions. This record may also contain information about disk group instead of drive, disk group data can be recognized by wMediaType field.

typedef struct {
  LPCSTR   lpszRootPath;
  LPCSTR   lpszVirtualRoot;
  LPCSTR   lpszVolumeLabel;
  LPCSTR   lpszFSName;
  INT   iMaxNameLength;
  DWORD   dwSerialNumber;
  WORD   wDiskNum;
  WORD   wMediaType;
  INT   iBytesPerSector;
  INT   iSectorsPerCluster;
  INT   iTotalClusters;
  INT   iFreeClusters;
  INT   iNumberOfFiles;
  INT   iNumberOfCompressedFiles;
  WORD   wNumberOfDirs;
} DISKINFORECORD, FAR *LPDISKINFOREC;

Members
lpszRootPath
Points to a null-terminated string containing drive root path. This could be in either regular form (<drive>:\), or in UNC format (\\<servername>\<sharename>).
lpszVirtualRoot
Points to a null-terminated string containing drive's virtual root. Virtual root is a special feature in WhereIsIt's catalog where only a part of folder tree is catalogued, with one of the folders posing as a virtual root folder. This field will be NULL if drive does not have a virtual root, or will be in form of "\\" (i.e. "\Virtual\Root\").
lpszVolumeLabel
Points to a null-terminated string containing drive volume label.
lpszFSName
Points to a null-terminated string containing file system name (for example: "FAT", "FAT32", "NTFS", "CDFS",...)
iMaxNameLength
Specifies the maximum length of file names allowed on this drive.
dwSerialNumber
Specifies disk's serial number.
wDiskNum
Specified user assigned disk number in the catalog.
wMediaType
Specifies media or disk type. If this structure contains disk group data, this field is set to DT_DISKGROUP. See Drive Type Constants.
iBytesPerSector
Specifies the number of bytes per sector.
iSectorsPerCluster
Specifies the number of sectors per cluster.
iTotalClusters
Specifies the number of all clusters on the media.
iFreeClusters
Specifies the number of free clusters on the media.
iNumberOfFiles
Specifies the number of files on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some files, this number may be lower than the actual number of files on disk. The content of compressed archive files is not included in this count.
iNumberOfCompressedFiles
Specifies the number of compressed files successfully retrieved from archive files during disk scan.
wNumberOfDirs
Specifies the number of folders on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some folders, this number may be lower than the actual number of folders on disk.

See also:
Drive Type Constants, ImportDesc_DiskInfo, ImportDesc_DiskInfoEx, FILEINFORECORD, FOLDERINFORECORD, ValidateRuntimePlugin


Description API 2.20 Functions

This is the list of all available functions defined in Description API version 2.10 in order to provide a way for WhereIsIt and description module to communicate. Some of these functions are required to be present and exported in description module, while some are optional. Function set has been kept as minimal as possible, in order to simplify programming of plugins. Programmer should be able to keep focus on how to get description from required source while WhereIsIt will take care of the rest.

Compared to the older Description API 1.0, DescAPI 2.0 adds additional functionality, such as ability to set disk names and new alias names, changes the way parameters are passed between WhereIsIt and plugins, includes additional support for error reporting, and more. Some of the functions from DescAPI 1.0 were replaced with advanced versions of those same functions, using the same function names with the Ex suffix. With DescAPI 2.xx, functions with the Ex suffix must be used.

DescAPI 2.10 was introduced later in WhereIsIt 3.20 as an extension to DescAPI 2.0, adding support for file name formatting plugins, and custom icons plugins. DescAPI 2.20 added runtime plugins support in WhereIsIt 3.50.

Description Module Initialization
ModuleInfoEx | ( required )
RegisterDescPlugins | ( required )
RegisterRuntimePlugins | ( required )
PluginDefaultStateProc | ( optional )
PluginCapabilitiesProc | ( optional )
ConfigPluginProc | ( optional )
ValidateRuntimePlugin | ( optional )
Description Importing
InitDescImport | ( optional )
DoneDescImport | ( optional )
InitVCLPlugin | ( optional )
ImportDesc_SameFileEx | ( required if plugins of type ptSameFile are registered)
ImportDesc_ParentItemEx | ( required if plugins of type ptParentItem are registered)
ImportDesc_FolderEx | ( required if plugins of type ptFolder are registered)
ImportDesc_ItemListEx | ( required if plugins of type ptItemList are registered)
ImportDesc_DiskInfoEx | ( required if plugins of type ptDiskInfo are registered)
Description Formatting
FormatDescription | ( required if plugins of type ptFormatting are registered)
FormatFileName | ( required if plugins of type ptFileNameFormatting are registered)
Thumbnails
ImportThumbnail | ( required if plugins of type ptThumbnails are registered)
ImportCustomIcon | ( required if plugins of type ptCustomIcons are registered)
Callback functions
RegisterPlugin | ( callback )
RegisterRuntimePlugin | ( callback )
RequireFile | ( callback )
StoreDescProc | ( callback )
StoreAliasProc | ( callback )

Legend:

required functions must be present and exported in your DLL in order to be used in WhereIsIt. WhereIsIt will not accept DLL missing those functions as a valid description module.

optional functions are provided for your convenience and will be called from WhereIsIt if they are exported in your DLL. You can use them if you need them with description importing.

callback functions are defined in WhereIsIt, their addresses will be passed to one of your DLL-defined functions as parameters. Those functions are provided for description modules to pass back information to WhereIsIt, or to employ some of WhereIsIt's capabilities during description importing.


ModuleInfoEx()

REQUIRED - DescAPI version: 2.xx

The ModuleInfoEx function is the first one called by WhereIsIt when collecting data about available plugins. This function will present your Description module's name, author, and version to WhereIsIt. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

VOID ModuleInfoEx(
LPMODULEINFOREC lpModuleInfo // points to the MODULEINFOREC structure that receives plugin details
);

Parameters
lpModuleInfo
Pointer to a MODULEINFOREC structure that receives the information about the plugin.

Return Values
None.

Remarks
If any of the strings in the MODULEINFOREC is returned empty, WhereIsIt will not register or use this module.

See also:
MODULEINFOREC, ModuleInfo


RegisterRuntimePlugins()

OPTIONALLY REQUIRED - DescAPI version: 2.20

The RegisterRuntimePlugins function is called during module initialization, at which time module is expected to register its ptRuntime plugins with WhereIsIt. A callback function address is provided as a parameter for registering plugins. A function with the name of RegisterRuntimePlugins must be exported from your DLL file if you are using runtime plugins.

VOID RegisterRuntimePlugins(
PROC lpRegisterRuntimePlugin, // pointer to a callback function
);

Parameters
lpRegisterRuntimePlugin
Points to the address of WhereIsIt-defined function to call when registering a new plugin. See the RegisterRuntimePlugin function description for details.

Return Values
None.

Remarks
You may want to store the address of lpRegisterRuntimePlugin callback procedure in case you will need it later, too. You can call again this procedure to re-register plugin in WhereIsIt in case some of data has changed - for example, plugin can have a configure dialog where user can change some details about the plugin.

See also:
RegisterRuntimePlugin


PluginDefaultStateProc()

OPTIONAL - DescAPI version: 2.xx

The PluginDefaultStateProc is an optional function that a description module may export. If a function with this name is exported in your DLL module, WhereIsIt will use it for all registered plugins in order to find out the default state of each plugin - this defines whether user is allowed to set the plugin to be enabled or disabled by default, or can plugin enforce the state itself. In any case, user is still allowed to manually enable or disable the plugin before each scan.

BYTE PluginDefaultStateProc(
 WORD wPluginID // ID of plugin WhereIsIt is inquiring the default state for
);

Parameters
wPluginID
Contains the plugin ID number for which WhereIsIt is inquireing the default state.

Return Values
The function should return one of the plugin default state constant.

See also:
RegisterPlugin, plugin default state values


PluginCapabilitiesProc()

OPTIONAL - DescAPI version: 2.xx

The PluginCapabilitiesProc is an optional function that gives feedback to WhereIsIt regarding plugin's importing capabilities. If available, this function will be called before each disk scanning operation begins, for each of active description plugins. Function is expected to return details on what kind of data will the plugin in question try to import during the following session - descriptions, alias names, or possibly both. Knowing this allows WhereIsIt to optimize plugins usage during disk updates, resulting in much faster scanning in most cases. This function only applies to description plugins, it is not used with formatting or thumbnail plugins.

It is highly recommended for all plugin modules to implement this function, although implementation is optional to preserve compatibility with older plugin modules. If this function is not available, WhereIsIt will assume that all description plugins will try to import descriptions only, without trying to provide alias names as well.

INT PluginCapabilitiesProc(
WORD wPluginID, // ID of plugin WhereIsIt is inquiring capabilities for
LPPLUGINCAPABILITIESREC PluginCapabilities // points to the PLUGINCAPABILITIESREC structure
);

Parameters
wPluginID
Contains the plugin ID number for which WhereIsIt is inquireing its importing capabilities.
PluginCapabilities
Points to the PLUGINCAPABILITIESREC structure, containing a set of boolean variables this function is expected to set accordingly to plugin's capabilities.

Return Values
The function should return zero in case of success, or a negative value in case of error.

See also:
PLUGINCAPABILITIESREC


ValidateRuntimePlugin()

OPTIONAL - DescAPI version: 2.20

WhereIsIt will call the ValidateRuntimePlugin function at any time when it needs to know whether a specific runtime plugin would handle a specific file, folder, or disk. WhereIsIt will filter out on its own all files that don't match plugin's file mask, for those that do, this function is called to give the plugin the chance to decide whether it is capable of handling them or not. Note that ValidateRuntimePlugin must not include lenghty processing and is expected to respond swiftly and promptly, otherwise users might experience annoying delays whenever the "Plugins" menu is opened.

BOOL RegisterPlugin(
 WORD wPluginID, // unique plugin's ID inside your description module
LPDISKINFOREC lpDiskInfo, // specifies plugin type
LPFOLDERINFOREC lpFolderInfo, // specifies the name of the plugin, as visible to users
LPFILEINFOREC lpFileInfo, // address of buffer to store plugin's target file masks
);

Parameters
wPluginID
Contains the ID number of plugin that is being questioned about handling specified item. If there are more plugins of type ptRuntime registered in your module, then the ValidateRuntimePlugin function must check the wPluginID parameter and consult the appropriate plugin.
lpDiskInfo
Points to the DISKINFORECORD structure, containing details about the media plugin is being questioned about. lpDiskInfo may also contain information about disk group instead of disk data, if disk group is the item plugin is being queried about.
lpFolderInfo
Points to the FOLDERINFORECORD structure. If the item plugin is being questioned about is a disk, this parameter is NULL.
lpFileInfo
Points to the FILEINFORECORD structure. If the item plugin is being questioned about is a folder or disk, this parameter is NULL.

Return Values
The function should return TRUE if indicated plugin accepts handling given item, or FALSE if the plugin passes on it.

See also:
RegisterRuntimePlugins, DISKINFORECORD, FOLDERINFORECORD, FILEINFORECORD


InitVCLPlugin()

OPTIONAL - DescAPI version: 2.20

The InitVCLPlugin is optional and only called if your description module exports a function by this name. This function is only useful for plugins written with Borland Delphi and using VCL. The one parameter is available to let the plugin know the value of WhereIsIt's TApplication.Handle property, which may be necessary to properly synchronize plugin's VCL to WhereIsIt's. As VCL is a visual controls library, plugins using this function are most likely to be runtime plugins, providing their own user interface within the plugin.

VOID InitVCLPlugin(
HANDLE hAppHandle // handle of TApplication VCL object
);

Parameters
hAppHandle
Contains the value of WhereIsIt's TApplication.Handle property. You can use this handle to properly synchronize a plugin using VCL with WhereIsIt's main window - just assign the value to plugin's Application.Handle property.

Return Values
None.

Remarks
Only to be used by plugins developed with Borland Delphi and using VCL.

See also:
InitDescImport, DoneDescImport


ImportDesc_SameFileEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_SameFileEx function is the main import function for plugins of type ptSameFile. WhereIsIt will call this function during disk scan every time when a file is found that matches the file mask of one of ptSameFile plugins in your module. WhereIsIt will expect from this function to do required processing on provided file (using requested description plugin), and return appropriate description and/or file alias name, if one could be extracted. Description and alias name are attached to that same file in catalog.
The ImportDesc_SameFileEx function is also used with all ptCDDB plugins, as the second stage. It is expected to return description for the provided track file (usually named like Cdtrack01.cda), after the CDDB information has already been retrieved by the ImportDesc_DiskInfoEx function.

INT ImportDesc_SameFileEx(
WORD wPluginID, // ID of description plugin to be used with provided file
LPIMPORTSAMEFILEREC lpImportSameFileInfo // points to the IMPORTSAMEFILEREC structure
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptSameFile registered in your description module, then the ImportDesc_SameFileEx function must check the wPluginID parameter and activate the proper plugin.
lpImportSameFileInfo
Points to the IMPORTSAMEFILEREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or alias name was not successful.

Remarks
If this function returns an error code, or returned description or alias name is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description or alias name for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types, IMPORTSAMEFILEREC, RequireFile, ImportDesc_SameFile


ImportDesc_ParentItemEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_ParentItemEx function is called by WhereIsIt when program needs to import description from one of module's ptParentItem plugins, and some of found files are matching plugin's file mask. Plugin will receive a list of matching files, and is expected to extract description to be assigned to the parent item (usually a parent folder, or an archive file, where found files are compressed in).

INT ImportDesc_ParentItemEx(
WORD wPluginID, // ID of description plugin to be used with provided file
LPIMPORTPARENTITEMREC lpImportParentItemInfo // points to the IMPORTPARENTITEMREC structure
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ParentItemEx function must check the wPluginID parameter and activate the proper plugin.
lpImportParentItemInfo
Points to the IMPORTPARENTITEMREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or alias name was not successful.

Remarks
If this function returns an error code, or returned description or alias name is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description or alias name for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types, IMPORTPARENTITEMREC, RequireFile, ImportDesc_ParentItem


ImportDesc_FolderEx()

OPTIONALLY REQUIRED - DescAPI version: 2.20

The ImportDesc_FolderEx function is called by WhereIsIt when the program is processing one of the folders, and requires a description or alias name for that folder. Plugin receives the drive and path of folder, and is expected to extract a description to be assigned to that folder in catalog.

INT ImportDesc_FolderEx(
WORD wPluginID, // ID of description plugin to be used with provided folder
LPIMPORTFOLDERREC lpImportFolderInfo // points to the IMPORTFOLDERREC structure
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptFolder registered in your description module, then the ImportDesc_FolderEx function must check the wPluginID parameter and activate the proper plugin.
lpImportFolderInfo
Points to the IMPORTFOLDERREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or alias name was not successful.

Remarks
If this function returns an error code, or returned description or alias name is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description or alias name for current item, but has lower priority set than the plugin just called.

See also:
Plugin Types, IMPORTFOLDERREC, RequireFile


ImportDesc_ItemListEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_ItemListEx function is a front-end for ptItemList - typed plugins. This function will be called by WhereIsIt when some of files are found to match the plugin's file mask, and plugin is given a chance to import descriptions from them. Since plugins of this type can retrieve multiple description from the source, a callback function is provided for a plugin to report the extracted descriptions back to WhereIsIt.

INT ImportDesc_ItemListEx(
WORD wPluginID, // ID of description plugin to be used with provided file
LPIMPORTITEMLISTREC lpImportItemListInfo // points to the IMPORTITEMLISTREC structure.
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptItemList registered in your description module, then the ImportDesc_ItemListEx function must check the wPluginID parameter and activate the proper plugin.
lpImportItemListInfo
Points to the IMPORTITEMLISTREC structure, containing a set of parameters to be used with this function, such as list of found files, callback functions to store descriptions, etc.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if an error has occured.

See also:
Plugin Types, IMPORTITEMLISTREC, RequireFile, ImportDesc_ItemList


ImportDesc_DiskInfoEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_DiskInfoEx function is called for plugins of ptDiskInfo type. Function receives as a parameter an address to DISKINFORECORD structure, containing many details about media, such as media type, size, volume label, serial number etc. The plugin may want to access some other source to retreive more detailed data about the media, such as network server, or even Internet-based database.

ImportDesc_DiskInfoEx function is also used with all ptCDDB plugins, as the first stage. Among parameters provided to this function there is also the CDDB query info, as retrieved during media scan and stored in catalog. If the plugin is a ptCDDB type, the ImportDesc_DiskInfoEx function should be used to connect to the CDDB server and retrieve the CD details. Description that applies to the media itself is returned through this function, while track information should be stored for subsequent ImportDesc_SameFileEx calls.

INT ImportDesc_DiskInfoEx(
WORD wPluginID, // ID of description plugin to be used with provided file
LPIMPORTDISKINFOREC lpImportDiskInfoRec // points to the IMPORTDISKINFOREC structure.
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to retrieve description for given disk. If there are more plugins of type ptDiskInfo registered in your description module, then the IImportDesc_DiskInfoEx function must check the wPluginID parameter and activate the proper plugin.
lpImportItemListInfo
Points to the IIMPORTDISKINFOREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or disk name was not successful.

See also:
Plugins types, IMPORTDISKINFOREC, RequireFile, ImportDesc_DiskInfo


FormatDescription

DescAPI version: 2.10

The FormatDescription function is called for plugins of ptFormatting type. Formatting plugins have a different role as they don't extract any descriptions on their own, but rather format extracted descriptions by other plugins. Typical task for formatting plugins are code page conversions, limiting the amount of text, etc.

INT FormatDescription(
WORD wPluginID, // ID of formatting plugin to be used
LPFORMATDESCREC lpFormatDescInfo // points to the FORMATDESCREC structure.
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to format given description. If there are more plugins of type ptFormatting registered in your plugins module, then the FormatDescription function must check the wPluginID parameter and activate the proper plugin.
lpFormatDescInfo
Points to the FORMATDESCREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if formatting description was not successful.

See also:
Plugins types, FORMATDESCREC


FormatFileName()

OPTIONALLY REQUIRED - DescAPI version: 2.10

The FormatFileName function is called for plugins of ptFileNameFormatting type. File name formatting plugins are used to modify a visual appearance of file and folder names being cataloged, namely allowing to adjust their character case. The ptFileNameFormatting plugins are given a chance to adjust file names before they are cataloged, and can do that according to user's settings, through plugin's configuration dialog. Note that plugins can only adjust the character case of file or folder names, but they must not change them in any other way - you can not use these plugins to store files and folders in catalog under different names as they appear on the media. WhereIsIt will refuse adjustments to file names if they differ in any other detail than in character case used.

INT FormatFileName(
WORD wPluginID, // ID of formatting plugin to be used
LPFORMATFILENAMEREC lpFormatFileNameInfo // points to the FORMATFILENAMEREC structure.
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to format given description. If there are more plugins of type ptFileNameFormatting registered in your plugins module, then the FormatFileName function must check the wPluginID parameter and activate the proper plugin.
lpFormatFileNameInfo
Points to the FORMATFILENAMEREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if converting file name was not successful.

See also:
Plugins types, FORMATFILENAMEREC


ImportThumbnail()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportThumbnail function is called for plugins of ptThumbnails, type, which have the task of importing standard bitmap images from supported image files. Those images are used by WhereIsIt either to generate downsampled thumbnails to be stored in the catalog, or they may be displayed in the internal image viewer in their full size. Importing images is not necessarily limited to image files only, like BMP, GIF, JPG etc. - plugins may in fact return image representations of any kind of documents that may either have thumbnails stored in their own file format, or image representation can be generated from its contents. For example, the latest Explorer versions can generate thumbnail images of HTML files on the fly - your plugin may want to do the same.

INT ImportThumbnail(
WORD wPluginID, // ID of thumbnail plugin to be used
LPIMPORTTHUMBNAILREC lpImportThumbnailInfo // points to the IMPORTTHUMBNAILREC structure
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to retrieve the image. If there are more plugins of type ptThumbnails registered in your plugins module, then the ImportThumbnail function must check the wPluginID parameter and activate the proper plugin.
lpImportThumbnailInfo
Points to the IMPORTTHUMBNAILREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving image was not successful.

See also:
Plugin Types, IMPORTTHUMBNAILREC


ImportCustomIcon()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportCustomIcon function is called for plugins of a ptCustomIcons type, which can import custom icons to be used for disks or folders in catalog instead of default system icons. Like thumbnails, custom icons are stored in catalogs. These plugins could be used to provide customized icons for drive or media of specific type, assign special icons to folders found to be holding certain kind of data, etc.

INT ImportCustomIcon((
WORD wPluginID, // ID of custom icon plugin to be used
LPIMPORTCUSTOMICONREC lpImportCustomIconInfo // points to the IMPORTCUSTOMICONREC structure.
);

Parameters
wPluginID
Contains the ID number of plugin that must be used to retrieve the image. If there are more plugins of type ptCustomIcons registered in your plugins module, then ImportCustomIcon function must check the wPluginID parameter and activate the appropriate plugin.
lpImportCistomIconInfo
Points to the IMPORTCUSTOMICONREC structure, containing a set of parameters to be used with this function.

Return Values
Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving icon was not successful.

See also:
Plugins types, IMPORTCUSTOMICONREC


RegisterRuntimePlugin()

CALLBACK - DescAPI version: 2.20

The RegisterRuntimePlugin function is provided by WhereIsIt, and is received as a parameter with the RegisterRuntimePlugins function. Your module will call RegisterRuntimePlugin from the RegisterRuntimePlugins function, once for each runtime plugin available in your module. Parameters to this function will provide everything WhereIsIt needs to know about the specified plugin.

INT RegisterPlugin(
 WORD wPluginID, // unique plugin's ID inside your description module
BYTE byPluginType, // specifies plugin type
LPTCSTR lpszPluginName, // specifies the name of the plugin, as visible to users
LPTCSTR lpszPluginMask, // address of the buffer to store plugin's target file masks
LPTCSTR lpszMenuOption, // address of the buffer to store plugin's menu option name
BOOL bRequiresMedia, // set to TRUE if plugin requires the media to be available
PROC lpConfigProc // address of function used to configure plugin
);

Parameters
wPluginID
Contains plugin's ID number to be used as a reference to this plugin. When WhereIsIt will call one of description-importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.
byPluginType
Specifies the type of plugin.
lpszPluginName
Specifies the name of the plugin, as users will see it in WhereIsIt.
lpszPluginMask
Points to a null-terminated string buffer where you can put a list of files or file masks. This is the list of files that your plugin can extract description(s) from. For example, a plugin that can extract information from WAV files and use it to describe those file will provide "*.WAV" as a plugin mask. If during disk scan one or more files complying with specified mask are encountered, your plugin will be called to extract description from them. Files or file masks in string should be provided in UPPER-CASE and separated with commas. Example: "README.TXT, *.NFO". Runtime plugins can also use the ValidateRuntimePlugin function to choose in runtime whether plugin will handle given item or not.
lpszMenuOption
Return here a null-terminated string representing the plugin's menu option, as it will be available in WhereIsIt's "Plugins" menu.
bRequiresMedia
Set this parameter to TRUE, if plugin needs to have media available in order to do its job. If so, WhereIsIt will request media to be inserted before calling out the plugin. If media is not required, set to FALSE.
lpConfigProc
Points to the function that can be used to setup your plugin. This function will be called if user will select your plugin in WhereIsIt, and click the Configure button. If your plugin does not provide users with ability to configure the plugin, you can specify NULL here as a parameter.

Return Values
If returned value is equal or greater to zero, plugin was successfully registered with WhereIsIt and return value is plugin's assigned serial number on WhereIsIt's plugin list. This value is informative only and will not be referenced later, you may safely discard it.

Negative return value is an error code, by the following table:

-1 | Invalid plugin type
-2 | Plugin with this ID already exists in your module
-3 | The name of plugin is invalid
-4 | File mask provided for plugin is invalid
-5 | Module does not export required description function for this plugin type

Note that error code -2 only applies if trying to register a plugin of different type than the one already registered with the same ID. If both plugins have the same ID and are of the same type, WhereIsIt will adjust settings for existing plugin instead of registering a new one.

See also:
RegisterRuntimePlugins, ValidateRuntimePlugin, plugin types


StoreAliasProc()

CALLBACK - DescAPI version: 1.0, 2.xx

The StoreAliasProc function is provided by WhereIsIt, and its address is sent as a parameter to the ImportDesc_ItemListEx function. The latter is used to import description using ptItemList plugins, meaning it will possibly return multiple alias names from single description source. The purpose of StoreAliasProc function is to provide a way for ImportDesc_ItemListEx function to send each retrieved "file name"-"alias" pair back to WhereIsIt, where the alias name will be stored in the catalog by the specified file.

BOOL StoreAliasProc(
LPTCSTR lpszFileName, // points to retrieved file name
LPTCSTR lpszAliasName // points to retrieved alias name
);

Parameters
lpszFileName
Points to the null-terminated string containing name and optional path to file or folder. WhereIsIt will try to find this item among catalogued data, and attach to it the description provided as the next parameter. See Remarks below for additional details.
lpszAliasName
Points to the null-terminated string containing an alias name retrieved by plugin that belongs to the lpszFileName parameter. Alias names may not contain line breaks. WARNING: Length of provided alias name should not exceed the maximum allowed description size, limited by MaxAliasLength global constant. If alias name is longer, it will be truncated.

Return Values
Returns TRUE if alias name was successfully stored in catalog, or FALSE, if provided file name was not found in the catalog.

Remarks
File or folder name can be provided in any of these three forms: name only, name with relative path from current folder, or file name with full path to item on the disk.
  • If target item is located in the same folder as description file is, you should provide the lpszFileName parameter as plain file name only, for example "TEST.EXE". This is also the most optimal choice from performance point of view since program is optimized to quickly find items in current folder. Most of description file formats like INDEX.TXT or FILES.BBS include list of files for current folder only, so you should be able to use this mode as much as possible.
  • If target is located in one of subfolders, relative to folder with the description file, you can use addressing with relative path, for example "FOLDER1\FOLDER2\...\TEXT.EXE". WhereIsIt will start in the current folder and look in catalog for subfolder named Folder1. If provided subfolder exist in catalog, WhereIsIt will look for file, too, and append description if file is found.
  • If you would like to provide descriptions for items anywhere on the disk, you will have to provide full path to the target file, including the drive letter, for example "F:\CURRENT\FOLDER1\FOLDER2\TEST.EXE".
    WARNING: This mode is only allowed when user is importing descriptions on demand, in already catalogued data, and will always fail when you try to use it during the disk scan.
Note: The last two modes can be considerably slower compared to the first one, especially if there are many subfolders in the disk you are scanning. If there are many items to import, end user may be experiencing considerable delays while your plugin is active.

See also:
ImportDesc_ItemListEx, StoreDescProc


Description API 2.20 Structures

The following constants and structures are defined as a part of Description API v2.20:

Structures

MODULEINFOREC
PLUGINCAPABILITIESREC
DISKINFORECORD
FOLDERINFORECORD
FILEINFORECORD
IMPORTSAMEFILEREC
IMPORTPARENTITEMREC
IMPORTFOLDERREC
IMPORTITEMLISTREC
IMPORTDISKINFOREC
FORMATDESCREC
FORMATFILENAMEREC
IMPORTTHUMBNAILREC
IMPORTCUSTOMICONREC

Constants

PluginType
MaxDescLength
MaxAliasLength
DriveTypes


MODULEINFOREC

DescAPI version: 2.xx

The MODULEINFOREC structure is used with the ModuleInfoEx function.

typedef struct {
  LPTCSTR   lpszModuleName;
  LPTCSTR   lpszAuthor;
  LPTCSTR   lpszVersion;
} MODULEINFOREC, FAR *LPMODULEINFOREC;

Members
lpszModuleName
Points to the buffer to receive the null-terminated string containing the module's name. String may not exceed 1024 bytes in length. Example: 'WhereIsIt Description Module'.
lpszAuthor
Points to the buffer to receive the null-terminated string containing the author's name. String may not exceed 1024 bytes in length. Example: 'Robert Galle'.
lpszVersion
Points to the buffer to receive the null-terminated string containing the version number. String may not exceed 1024 bytes in length. Example: '0.90 beta'.

See also:
ModuleInfoEx


PLUGINCAPABILITIESREC

DescAPI version: 2.xx

The PLUGINCAPABILITIESREC structure is used with the PluginCapabilitiesProc function.
typedef struct {
  BOOL      bImportingDesc;
  BOOL      bImportingAlias;
} PLUGINCAPABILITIESREC, FAR *LPPLUGINCAPABILITIESREC;

Members
bImportingDesc
Set to TRUE if plugin will attempt to import descriptions.
bImportingAlias
Set to TRUE if plugin will attempt to import alias names.

See also:
PluginCapabilitiesProc


FOLDERINFORECORD

DescAPI version: 2.20

The FOLDERINFORECORD structure is used with ValidateRuntimePlugin function.

typedef struct {
  LPCSTR   lpszFolderPath;
  INT64	   iSize;
  BYTE     bAttribute;
  INT      iDateCreated;
  INT      iDateModified;
  INT      iDateAccessed;
} FOLDERINFORECORD, FAR *LPFOLDERINFOREC;

Members
lpszFolderPath
Points to a null-terminated string with the path to the folder on the media.
iSize
Specifies the size of the folder in bytes.
bAttribute
Specifies folder's file attributes.
iDateCreated
Contains the date and time when folder was created (DOS date-and-time stamp format)
iDateModified
Contains the date and time when folder was last modified (DOS date-and-time stamp format)
iDateAccessed
Contains the date and time when folder was last accessed (DOS date-and-time stamp format)

See also:
DISKINFORECORD, FILEINFORECORD, ValidateRuntimePlugin


FILEINFORECORD

DescAPI version: 2.20

The FILEINFORECORD structure is used with ValidateRuntimePlugin function.

typedef struct {
  LPCSTR   lpszFileName;
  INT64	   iSize;
  BYTE     bAttribute;
  INT      iDateCreated;
  INT      iDateModified;
  INT      iDateAccessed;
} FOLDERINFORECORD, FAR *LPFOLDERINFOREC;

Members
lpszFileName
Points to a null-terminated string holding the file name of given file.
iSize
Contains the size of the file in bytes.
bAttribute
Specifies file attributes for given file.
iDateCreated
Contains the date and time when file was created (DOS date-and-time stamp format)
iDateModified
Contains the date and time when file was last modified (DOS date-and-time stamp format)
iDateAccessed
Contains the date and time when file was last accessed (DOS date-and-time stamp format)

See also:
DISKINFORECORD, FOLDERINFORECORD, ValidateRuntimePlugin


IMPORTSAMEFILEREC

DescAPI version: 2.xx

The The IMPORTSAMEFILEREC structure is used as a parameter with the ImportDesc_SameFileEx function.

typedef struct {
  LPTCSTR   lpszFileName;
  LPTCSTR   lpszDesc;
  LPTCSTR   lpszAliasName;
  PROC      lpRequireFileProc;
  WORD      wMaxDescSize;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTSAMEFILEREC, FAR *LPIMPORTSAMEFILEREC;

Members
lpszFileName
Points to the null-terminated string, containing a full path to the file waiting to be described. Provide this parameter to the RequireFile function before your plugin attempts to open the file.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant). If description is set longer, it is likely to cause severe errors in program!
lpszAliasName
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with item's alias name. Alias names may not contain line breaks.
WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for alias names (provided in MaxAliasLength global constant). If alias name is set longer, it is likely to cause severe errors in program!
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
RequireFile, ImportDesc_SameFileEx


IMPORTPARENTITEMREC

DescAPI version: 2.xx

The IMPORTPARENTITEMREC structure is used as a parameter with the ImportDesc_ParentItemEx function.
typedef struct {
  LPTCSTR   lpszParentName;
  LPTCSTR   lpszFileList;
  LPTCSTR   lpszDesc;
  LPTCSTR   lpszAliasName;
  PROC      lpRequireFileProc;
  WORD      wMaxDescSize;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTPARENTITEMREC, FAR *LPIMPORTPARENTITEMREC;

Members
lpszParentName
Points to the address of a null-terminated string, holding a full path to the parent item (item that will receive description provided by calling this function).
lpszFileList
Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:
  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0
where #0 represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!
lpszAliasName
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with item's alias name. Alias names may not contain line breaks.
WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxAliasLength global constant). If description is set longer, it is likely to cause severe errors in program!
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
RequireFile, ImportDesc_ParentItemEx


IMPORTFOLDERREC

DescAPI version: 2.xx

The IMPORTFOLDERREC structure is used as a parameter with the ImportDesc_FolderEx function.
typedef struct {
  LPTCSTR   lpszDrive;
  LPTCSTR   lpszFolderPath;
  LPTCSTR   lpszDesc;
  LPTCSTR   lpszAliasName;
  PROC      lpRequireFileProc;
  WORD      wMaxDescSize;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTFOLDERREC, FAR *LPIMPORTFOLDERREC;

Members
lpszDrive
Points to the address of a null-terminated string, holding a drive root path. This could be in either regular form (:\), or in UNC format (\\\).
lpszFolderPath
Points to the address of a null-terminated string, holding a path to the folder plugin is expected to process.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!
lpszAliasName
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with item's alias name. Alias names may not contain line breaks.
WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxAliasLength global constant). If description is set longer, it is likely to cause severe errors in program!
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
RequireFile, ImportDesc_FolderEx


IMPORTITEMLISTREC

DescAPI version: 2.xx

The IMPORTITEMLISTREC structure is used as a parameter with the ImportDesc_ItemListEx function.

typedef struct {
  LPTCSTR   lpszParentName;
  LPTCSTR   lpszFileList;
  PROC      lpRequireFileProc;
  PROC      lpStoreDescProc;
  PROC      lpStoreAliasProc;
  WORD      wMaxDescSize;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTITEMLISTREC, FAR *LPIMPORTITEMLISTREC;

Members
lpszParentName
Points to the address of a null-terminated string, holding the full path to parent item (item that will receive description provided by calling this function).
lpszFileList
Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:
  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0
where #0 represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file.
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
lpStoreDescProc
Holds the address of StoreDescProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreDescProc for more details.
lpStoreAliasProc
Holds the address of StoreAliasProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreAliasProc for more details.
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
ImportDesc_ItemListEx, RequireFile, StoreDescProc, StoreAliasProc


IMPORTDISKINFOREC

DescAPI version: 2.xx

The IMPORTDISKINFOREC structure is used as a parameter with the ImportDesc_DiskInfoEx function.

typedef struct {
  LPDISKINFOREC lpDiskInfo;
  LPTCSTR   lpszDesc;
  LPTCSTR   lpszDiskName;
  LPTCSTR   lpszCDDBQueryID;
  WORD      wMaxDescSize;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTDISKINFOREC, FAR *LPIMPORTDISKINFOREC;

Members
lpDiskInfo
Points to the DISKINFORECORD structure, containing details about media that is being scanned.
lpszDesc
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!
lpszDiskName
Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with disk's name. Disk names may not contain line breaks, and should be of a reasonable length, say max. 80 characters.
lpszCDDBQueryID
Specifies the CDDB query string for current media, if one is available. The CDDB query string is retrieved during media scan and stored in catalog. This data would usually only be used by ptCDDB type plugins.
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
ImportDesc_DiskInfoEx, DISKINFORECORD, RequireFile


FORMATDESCREC

DescAPI version: 2.10

The FORMATDESCREC structure is used as a parameter with the FormatDescription function.

typedef struct {
  LPTCSTR   lpszDesc;
  WORD      wMaxDescSize;
  LPTCSTR   lpszSourceModuleFile;
  WORD      wSourcePluginID;
  HANDLE    hOwnerWnd;
} FORMATDESCREC, FAR *LPFORMATDESCREC;

Members
lpszDesc
Points to the buffer (reserved by WhereIsIt) when the existing description string is provided. The plugin is expected to provide the resulting string in that same buffer, replacing provided string with the new version.
WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant. If description is set longer, it is likely to cause severe errors in program!
wMaxDescSize
Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.
lpszSourceModuleFile
Points to the address of a null-terminated string, holding the file name of the description module, containing the plugin that was used for extracting current description. This information can be used if formatting plugin is only intended to handle descriptions imported by specific plugins.
wSourcePluginID
Contains the ID of the plugin that was used for extracting current description. This information can be used if formatting plugin is only intended to handle descriptions imported by specific plugins.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
FormatDescription


FORMATFILENAMEREC

DescAPI version: 2.10

The FORMATFILENAMERECstructure is used as a parameter with the FormatFileName function.

typedef struct {
  LPTSTR    lpszFileName;
  LPTSTR    lpszFullPath;
  BOOL      bIsDirectory;
  BOOL      bIsCompressed;
  HANDLE    hOwnerWnd;
} FORMATFILENAMEREC, FAR *LPFORMATFILENAMEREC;

Members
lpszFileName
Points to the buffer containing file or folder name. Plugin should modify the case of characters in this buffer as desired, but it must not change the contents in any other way. WhereIsIt checks the modified name and if the resulting buffer differs from the original in any detail other than character case, plugin's result will be discarded and original file name used instead.
lpszFullPath
Points to the buffer where the full path to file or folder is stored, including the drive and file/folder name. If lpszFileName is a file compressed inside archive file, this parameter specifies a full path to the archive file.
bIsDirectory
Set to TRUE if lpszFile name specifies a folder. If FALSE, lpszFile name specifies a regular or compressed (archive) file.
bIsCompressed
Set to TRUE if lpszFile is a file compressed inside an archive file.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
FormatFileName


IMPORTTHUMBNAILREC

DescAPI version: 2.xx

The IMPORTTHUMBNAILREC structure is used as a parameter with the ImportThumbnail function.

typedef struct {
  LPTCSTR   lpszFileName;
  WORD      wXSize;
  WORD      wYSize;
  HANDLE    hBitmapHandle;
  PROC      lpRequireFileProc;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTTHUMBNAILREC, FAR *LPIMPORTTHUMBNAILREC;

Members
lpszFileName
Points to the null-terminated string, containing a full path to the image file. Provide this parameter to the RequireFile function before your plugin attempts to open the file.
wXSize, wYSize
Provide the target pixel size of imported image. Usually those values would indicate the size of thumbnails, as it is user-defined in WhereIsIt. Note that this values are informative only, plugins are not required to resample images to specified size as WhereIsIt can handle that. Usually, plugins will load images in their full size and let WhereIsIt to do any necessary processing to get a thumbnail out of it. Plugins may, however, do resampling or other image processing themselves, if they can do a better job that WhereIsIt's built-in capabilities. If the returned image is within specified size (or smaller), WhereIsIt will not process it any further.
Please note: If wXSize and wYSize are reported as 0, plugin should always return the picture in its native size, even if it includes resampling capabilities on its own. 0 values indicate that imported picture will not be used for generating a thumbnail, but it will be displayed in the internal image viewer in its full size.
hBitmapHandle
Plugin is expected to store the bitmap handle of loaded image to this field. The handle should be allocated by the plugin, but will be released later by WhereIsIt, when the bitmap is no longer needed.
lpRequireFileProc
This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
ImportThumbnail, RequireFile


IMPORTCUSTOMICONREC

DescAPI version: 2.10

The IMPORTCUSTOMICONREC structure is used as a parameter with the ImportCustomIcon function.

typedef struct {
  LPTSTR    lpszItemPath;
  HANDLE    hIconHandle;
  BOOL      bSilentMode;
  HANDLE    hOwnerWnd;
} IMPORTCUSTOMICONREC, FAR *LPIMPORTCUSTOMICONREC;

Members
lpszItemPath
Points to the buffer holding the path of drive or folder custom icon is being imported for, for example "C:", "D:\Folder1\Folder", "\\SERVER\DRIVE\Folder", etc. The trailing backslash is not included.
hIconHandle
Plugin is expected to store the icon handle to this field. The handle should be allocated by the plugin, but will be released later by WhereIsIt, when the icon is no longer needed.
bSilentMode
Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.
hOwnerWnd
Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:
ImportCustomIcon


PluginDefaultStateProc

Plugin Default State Constants

This is the list of currently supported default states for plugins, used as return values with the optional PluginDefaultStateProc function. This states can be used to advise WhereIsIt on how specific plugin should be used - is it always enabled or disabled by default, or does it remember the last user's setting.
// --- DescAPI 2.0 only ---

#define pdsUserDefined_EnabledFirstTime    0
#define pdsUserDefined_DisabledFirstTime   1
#define pdsForceAlwaysEnabled              2
#define pdsForceAlwaysDisabled             3
pdsUserDefined_EnabledFirstTime
Plugin remembers the last global setting in WhereIsIt, user can select himself if plugin will be enabled or disabled by default. If plugin is new to WhereIsIt, it is set as enabled by default. This is the recommended setting for all normal plugins.
pdsUserDefined_DisabledFirstTime
Plugin remembers the last global setting in WhereIsIt, user can select himself if plugin will be enabled or disabled by default. If plugin is new to WhereIsIt, it is set as disabled by default. This setting should be used for plugins that are not likely or wanted to be used in normal circumstances - setting them as disabled by default allows new users who are not yet familiar with plugins not to be confused with the effects of such plugin.
pdsForceAlwaysEnabled
Forces the plugin to be always enabled by default, regardless of previous user's setting. User can still disable the plugin, but has to do so manually before each scan. Use with caution and only with a good reason.
pdsForceAlwaysDisabled
Forces the plugin to be always disabled by default, regardless of previous user's setting. User can still enable the plugin, but has to do so manually before each scan. Use this setting for plugins that are for very special purposes only and are only to be used in certain circumstances.

See also:
PluginDefaultStateProc


MaxAliasLength

DescAPI version: 2.xx

The MaxAliasLength constant defines the maximum allowed alias name length for items in WhereIsIt's catalogs. This constant is only defined in Description API 2.0.

Description API 2.xx:

#define MAXALIASLENGTH 255 // maximum allowed alias name length in bytes

WARNING: Alias names may not exceed the above length when being copied to the result buffer, or they can cause severe errors in the program.

See also:
ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx, FormatDescription, StoreAliasProc


MaxDescLength

DescAPI version: 2.xx

The MaxDescLength constant defines the maximum allowed description length for items in WhereIsIt's catalogs. This constant contains a different value in DescAPI 1.0 and DescAPI 2.0:

Description API 1.0:

#define MAXDESCLENGTH 4096 // maximum allowed description length in bytes (4 KB)

Description API 2.xx:

#define MAXDESCLENGTH 32768 // maximum allowed description length in bytes (32 KB)

WARNING: Description plugins may not exceed description length when being copied to the result buffer, or they can cause severe errors in the program.

See also:
DescAPI version: 1.0
ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList, ImportDesc_DiskInfo, StoreDescProc

DescAPI version: 2.xx
ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx, ImportDesc_DiskInfoEx, FormatDescription, StoreDescProc